lets_plot.geo_data.NamesGeocoder

class lets_plot.geo_data.NamesGeocoder(level: Optional[Union[str, lets_plot.geo_data.gis.request.LevelKind]] = None, request: Optional[Union[str, List[str], pandas.core.series.Series]] = None)

Do not use this class explicitly.

Instead you should construct its objects with special functions: geocode(), geocode_cities(), geocode_counties(), geocode_states(), geocode_countries(), reverse_geocode().

__init__(level: Optional[Union[str, lets_plot.geo_data.gis.request.LevelKind]] = None, request: Optional[Union[str, List[str], pandas.core.series.Series]] = None)

Initialize self.

scope(scope) → lets_plot.geo_data.geocoder.NamesGeocoder

Limit area of interest to resolve an ambiguity.

Parameters

scope (str or Geocoder) – Area of interest. If it is of str type then it should be the geo-object name. If it is of Geocoder type then it must contain only one object.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
scope = geocode_states('Kentucky')
city = geocode_cities('Franklin').scope(scope).get_boundaries()
display(city)
ggplot() + geom_map(data=city) + ggtitle('Franklin, Kentucky')

The geodata is provided by © OpenStreetMap contributors and is made available here under the Open Database License (ODbL).

	city	found name	geometry
0	Franklin	Franklin	MULTIPOLYGON (((-86.50721 36.72540, -86.50738 ...

highlights(v: bool)

Add matched string to geocodes DataFrame. Doesn’t affect GeoDataFrame.

Parameters

v (bool) – If True geocodes DataFrame will contain column ‘highlights’ with string that matched the name.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

from lets_plot.geo_data import *
geocode(names='OH').allow_ambiguous().highlights(True).get_geocodes()

	id	state	found name	highlights
0	324123	OH	Ohio	[OH, US-OH]
1	4559203	OH	Omaheke Region	[OH, NA-OH]

countries(countries)

Set parents for ‘country’ level to resolve an ambiguity or to join geometry with data via multi-key.

Parameters

countries (str or Geocoder or list) – Parents for ‘country’ level. If it is of str type then it should be the country name. If it is of Geocoder type then it must contain the same number of values as the number of names of Geocoder. If it is of list type then it must be the same size as the number of names of Geocoder.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
cities = geocode_cities(['Boston', 'Boston']).countries(['US', 'UK']).get_centroids()
display(cities)
ggplot() + geom_livemap() + geom_point(data=cities, color='red', size=5)

	city	found name	country	geometry
0	Boston	Boston	US	POINT (-71.08845 42.31104)
1	Boston	Boston	UK	POINT (-0.04871 52.97437)

states(states) → lets_plot.geo_data.geocoder.NamesGeocoder

Set parents for ‘state’ level to resolve an ambiguity or to join geometry with data via multi-key.

Parameters

states (str or Geocoder or list) – Parents for ‘state’ level. If it is of str type then it should be the state name. If it is of Geocoder type then it must contain the same number of values as the number of names of Geocoder. If it is of list type then it must be the same size as the number of names of Geocoder.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
states = geocode_states(['Massachusetts', 'New York'])
cities = geocode_cities(['Boston', 'Boston']).states(states).get_centroids()
display(cities)
ggplot() + geom_livemap() + geom_point(data=cities, color='red', size=5)

	city	found name	state	geometry
0	Boston	Boston	Massachusetts	POINT (-71.08845 42.31104)
1	Boston	North Boston	New York	POINT (-78.77965 42.67952)

counties(counties: Optional[Union[str, lets_plot.geo_data.geocodes.Geocodes, lets_plot.geo_data.geocoder.Geocoder, lets_plot.geo_data.gis.request.MapRegion, List]]) → lets_plot.geo_data.geocoder.NamesGeocoder

Set parents for ‘county’ level to resolve an ambiguity or to join geometry with data via multi-key.

Parameters

counties (str or Geocoder or list) – Parents for ‘county’ level. If it is of str type then it should be the county name. If it is of Geocoder type then it must contain the same number of values as the number of names of Geocoder. If it is of list type then it must be the same size as the number of names of Geocoder.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
counties = geocode_counties(['Suffolk County', 'Erie County'])\
           .states(['Massachusetts', 'New York'])
cities = geocode_cities(['Boston', 'Boston']).counties(counties).get_centroids()
display(cities)
ggplot() + geom_livemap() + geom_point(data=cities, color='red', size=5)

	city	found name	county	geometry
0	Boston	Boston	Suffolk County	POINT (-71.08845 42.31104)
1	Boston	North Boston	Erie County	POINT (-78.77965 42.67952)

ignore_not_found() → lets_plot.geo_data.geocoder.NamesGeocoder

Remove not found objects from the result.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
countries = geocode_countries(['Germany', 'Hungary', 'Czechoslovakia'])\
            .ignore_not_found().get_boundaries(6)
display(countries)
ggplot() + geom_map(aes(fill='found name'), data=countries, color='white')

	country	found name	geometry
0	Germany	Deutschland	MULTIPOLYGON (((8.45947 47.59135, 8.48145 47.5...
1	Hungary	Magyarország	MULTIPOLYGON (((17.31445 45.98170, 17.29248 45...

ignore_all_errors() → lets_plot.geo_data.geocoder.NamesGeocoder

Remove objects that have multiple matches from the result.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
cities = geocode_cities(['Boston', 'Worcester', 'Barnstable'])\
         .ignore_all_errors().get_centroids()
display(cities)
ggplot() + geom_livemap() + geom_point(data=cities, color='red', size=5)

	city	found name	geometry
0	Boston	Boston	POINT (-71.08845 42.31104)
1	Barnstable	Barnstable	POINT (-70.36277 41.66125)

allow_ambiguous() → lets_plot.geo_data.geocoder.NamesGeocoder

For objects that have multiple matches add all of them to the result.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
cities = geocode_cities('Worcester').scope('US')\
         .allow_ambiguous().get_centroids()
display(cities)
ggplot() + geom_livemap() + geom_point(data=cities, color='red', size=5)

	city	found name	geometry
0	Worcester	Worcester	POINT (-71.81547 42.26787)
1	Worcester	Worcester	POINT (-72.57245 44.41330)
2	Worcester	Worcester Township	POINT (-75.34387 40.19262)

where(name: str, county: Optional[Union[str, lets_plot.geo_data.geocodes.Geocodes, Geocoder, lets_plot.geo_data.gis.request.MapRegion, List]] = None, state: Optional[Union[str, lets_plot.geo_data.geocodes.Geocodes, Geocoder, lets_plot.geo_data.gis.request.MapRegion, List]] = None, country: Optional[Union[str, lets_plot.geo_data.geocodes.Geocodes, Geocoder, lets_plot.geo_data.gis.request.MapRegion, List]] = None, scope: Optional[Union[str, lets_plot.geo_data.geocodes.Geocodes, Geocoder, shapely.geometry.Polygon]] = None, closest_to: Optional[Union[lets_plot.geo_data.geocodes.Geocodes, shapely.geometry.Point]] = None) → NamesGeocoder

Allows to resolve ambiguity by setting up extra parameters. Combination of name, county, state, country identifies a row with an ambiguity. If row with given names does not exist error will be generated.

Parameters

• name (str) – Name in Geocoder that needs better qualification.

• county (str) – If Geocoder has parent counties this field must be present to identify a row for the name.

• state (str) – If Geocoder has parent states this field must be present to identify a row for the name.

• country (str) – If Geocoder has parent countries this field must be present to identify a row for the name.

• scope (str or Geocoder or shapely.geometry.Polygon) – Limits area of geocoding. If parent country is set then error will be generated. If type is a str - geoobject should have geocoded scope in parents. If type is a Geocoder - geoobject should have geocoded scope in parents. Scope should contain only one entry. If type is a shapely.geometry.Polygon - geoobject centroid should fall into bbox of the polygon.

• closest_to (Geocoder or shapely.geometry.Point) – Resolve ambiguity by taking closest geoobject.

Returns

Geocoder object specification.

Return type

NamesGeocoder

Examples

from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
city = geocode_cities('Warwick').countries('US')                   .where(name='Warwick', country='US', scope='Massachusetts').get_centroids()
display(city)
ggplot() + geom_livemap() + geom_point(data=city, color='red', size=5)

	city	found name	country	geometry
0	Warwick	Warwick	US	POINT (-72.33655 42.66792)

from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
closest_city = geocode_cities('Birmingham').get_centroids().iloc[0].geometry
city = geocode_cities('Warwick')\
       .where(name='Warwick', closest_to=closest_city).get_centroids()
display(city)
ggplot() + geom_livemap() + geom_point(data=city, color='red', size=5)

	city	found name	geometry
0	Warwick	Warwick	POINT (-1.58228 52.30154)

get_boundaries(resolution=None) → GeoDataFrame

Return boundaries for given regions in the form of GeoDataFrame.

Parameters

resolution (int or str) – Boundaries resolution.

Returns

Table of data.

Return type

GeoDataFrame

Note

If resolution has int type, it may take one of the following values:

• 1-3 for world scale view,

• 4-6 for country scale view,

• 7-9 for state scale view,

• 10-12 for county scale view,

• 13-15 for city scale view.

Here value 1 corresponds to maximum performance and 15 - to maximum quality.

If resolution is of str type, it may take one of the following values:

• ‘world’ corresponds to int value 2,

• ‘country’ corresponds to int value 5,

• ‘state’ corresponds to int value 8,

• ‘county’ corresponds to int value 11,

• ‘city’ corresponds to int value 14.

Here value ‘world’ corresponds to maximum performance and ‘city’ - to maximum quality.

The resolution choice depends on the type of displayed area. The number of objects also matters: one state looks good on a ‘state’ scale while 50 states is a ‘country’ view.

It is allowed to use any resolution for all regions. For example, ‘city’ scale can be used for a state to get a more detailed boundary when zooming in, or ‘world’ for a small preview.

If resolution is not specified (or equal to None), it will be auto-detected. Auto-detection by level_kind is used for geocoding and the number of objects. In this case performance is preferred over quality. The pixelated geometries can be obtained. Use explicit resolution or inc_res() function for better quality.

If the number of objects is equal to n, then resolution will be the following:

• For countries: if n < 3 then resolution=3, else resolution=1.

• For states: if n < 3 then resolution=7, if n < 10 then resolution=4, else resolution=2.

• For counties: if n < 5 then resolution=10, if n < 20 then resolution=8, else resolution=3.

• For cities: if n < 5 then resolution=13, if n < 50 then resolution=4, else resolution=3.

Examples

from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
countries = geocode_countries(['Germany', 'Poland']).inc_res().get_boundaries()
display(countries)
ggplot() + geom_map(aes(fill='found name'), data=countries, color='white')

	country	found name	geometry
0	Germany	Deutschland	MULTIPOLYGON (((7.47070 49.15297, 7.47070 49.1...
1	Poland	Polska	MULTIPOLYGON (((23.59863 51.89005, 23.64258 51...

get_centroids() → GeoDataFrame

Return centroids (Point geometry) for given regions in form of GeoDataFrame.

Returns

Table of data.

Return type

GeoDataFrame

Examples

from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
countries = geocode_countries(['Germany', 'Poland']).get_centroids()
display(countries)
ggplot() + geom_point(aes(color='found name'), data=countries, size=10)

	country	found name	geometry
0	Germany	Deutschland	POINT (10.57925 51.16420)
1	Poland	Polska	POINT (19.15683 51.91905)

get_geocodes() → DataFrame

Return metadata for given regions.

Returns

Table of data.

Return type

DataFrame

Examples

from lets_plot.geo_data import *
geocode_countries(['Germany', 'Russia']).get_geocodes()

	id	country	found name
0	102955	Germany	Deutschland
1	120379	Russia	Россия

get_limits() → GeoDataFrame

Return bboxes (Polygon geometry) for given regions in form of GeoDataFrame. For regions intersecting anti-meridian bbox will be divided into two parts and stored as two rows.

Returns

Table of data.

Return type

GeoDataFrame

Examples

from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
countries = geocode_countries(['Germany', 'Poland']).get_limits()
display(countries)
ggplot() + geom_rect(aes(fill='found name'), data=countries, color='white')

	country	found name	geometry
0	Germany	Deutschland	POLYGON ((15.04181 47.27011, 15.04181 55.05857...
1	Poland	Polska	POLYGON ((24.14578 49.00205, 24.14578 54.83565...

inc_res(delta=2)

Increase auto-detected resolution for boundaries.

Parameters

delta (int, default=2) – Value that will be added to auto-detected resolution.

Returns

Geocoder object specification.

Return type

Geocoder

Examples

from IPython.display import display
from lets_plot import *
from lets_plot.geo_data import *
LetsPlot.setup_html()
countries = geocode_countries(['Germany', 'Poland']).inc_res().get_boundaries()
display(countries)
ggplot() + geom_map(aes(fill='found name'), data=countries, color='white')

	country	found name	geometry
0	Germany	Deutschland	MULTIPOLYGON (((7.47070 49.15297, 7.47070 49.1...
1	Poland	Polska	MULTIPOLYGON (((23.59863 51.89005, 23.64258 51...